NAME¶
authselect - select system identity and authentication
sources.
SYNOPSIS¶
authselect [--debug] [--trace] [--warn] command [command options]
DESCRIPTION¶
Authselect is a tool to configure system identity and
authentication sources and providers by selecting a specific profile.
Profile is a set of files that describes how the resulting system
configuration will look like. When a profile is selected, authselect
will create nsswitch.conf(5) and PAM(8) stack to use identity and
authentication sources defined by the profile.
If the provided profile set is not sufficient, the administrator
may create a custom profile by putting it in a special profile directory
(/etc/authselect/custom). By doing so, the profile is immediately usable by
authselect. See authselect-profiles(5) for more information on
extending existing profiles.
OPT-IN TO AUTHSELECT¶
Authselect will not touch your existing configuration unless it
has already been created by it. If you want to start using authselect to
configure your system authentication, please call authselect select
with --force parameter first (e.g. authselect select sssd
--force). The --force parameter tells authselect that it is all
right to overwrite existing non-authselect configuration (see description
below). Using the --force parameter will automatically generate a
backup of your current configuration so if you wish to go back you can
restore it with authselect backup-restore command (see description
below).
AVAILABLE COMMANDS¶
To list all available commands run authselect without any
parameters. To print help for the selected command run authselect COMMAND
--help.
select profile_id [features] [-f, --force] [-q, --quiet]
[-b] [--backup=NAME]
Activate desired profile. See profile description with
show command, to list profile specific optional features.
--force, -f
Write changes even if the previous configuration was not
created by authselect but by other tool or by manual changes. This option will
automatically backup system files before writing any change unless
--nobackup option is set.
-b
Backup system files before activating the selected
profile. The backup will be stored at /var/lib/authselect/backups/NAME.
Current time with unique string is used as a name of the backup. This is a
shortcut for --backup=.
--backup=NAME
Backup system files before activating the selected
profile. The backup will be stored at /var/lib/authselect/backups/NAME.
Current time with unique string is used as a name if no value is
provided.
--nobackup
Do not backup system configuration even if --force
is set.
--quiet, -q
The command will not print any informational message such
as additional profile requirements or backup location. Errors are still being
print.
apply-changes [-b] [--backup=NAME]
Re-apply currently selected profile. If the profile
templates were updated this command can be used to regenerate current system
configuration in order to apply these changes on the system. This command will
only re-apply the changes if the existing configuration is a valid authselect
configuration, otherwise an error is returned.
-b
Backup system files before applying changes. The backup
will be stored at /var/lib/authselect/backups/NAME. Current time with unique
string is used as a name of the backup. This is a shortcut for
--backup=.
--backup=NAME
Backup system files before applying changes. The backup
will be stored at /var/lib/authselect/backups/NAME. Current time with unique
string is used as a name if no value is provided.
list
List available profiles.
list-features profile_id
List all features available in given profile.
Note: This will only list the features without any
description. Please, read the profile documentation with show to see
what the features do.
show profile_id
Print information about the profile.
requirements profile_id [features]
Print information about profile requirements.
current [-r, --raw]
Print information about currently selected profiles. If
--raw option is specified, the command will print raw parameters as
they were passed to select command instead of formatted output.
check
Check if the current configuration is valid (it was
either created by authselect or there are no leftovers from previous
authselect configuration).
test profile_id [options] [features]
Print content of files generated by
authselect
without actually writing anything to system configuration.
-a, --all
Print content of all files.
-n, --nsswitch
Print nsswitch.conf content.
-s, --system-auth
Print system-auth content.
-p, --password-auth
Print password-auth content.
-c, --smartcard-auth
Print smartcard-auth content.
-f, --fingerprint-auth
Print fingerprint-auth content.
-o, --postlogin
Print postlogin content.
-d, --dconf-db
Print dconf database content.
-l, --dconf-lock
Print dconf lock content.
enable-feature feature [-b] [--backup=NAME] [-q,
--quiet]
Enable feature in the currently selected profile.
-b
Backup system files before enabling feature. The backup
will be stored at /var/lib/authselect/backups/NAME. Current time with unique
string is used as a name of the backup. This is a shortcut for
--backup=.
--backup=NAME
Backup system files before enabling feature. The backup
will be stored at /var/lib/authselect/backups/NAME. Current time with unique
string is used as a name if no value is provided.
--quiet, -q
The command will not print any informational message such
as additional profile requirements or backup location. Errors are still being
print.
disable-feature feature [-b] [--backup=NAME]
Disable feature in the currently selected profile.
-b
Backup system files before disabling feature. The backup
will be stored at /var/lib/authselect/backups/NAME. Current time with unique
string is used as a name of the backup. This is a shortcut for
--backup=.
--backup=NAME
Backup system files before disabling feature. The backup
will be stored at /var/lib/authselect/backups/NAME. Current time with unique
string is used as a name if no value is provided.
create-profile NAME [--vendor,-v] [options]
Create a new custom profile named
NAME. The
profile can be based on an existing profile in which case the new profile
templates are either copied from the base profile or symbolic links to these
files are created if such option is selected.
--vendor,-v
The new profile is a vendor profile instead of a custom
profile. See
authselect-profiles(5) for more information on profile
types.
--base-on=BASE-ID, -b=BASE-ID
The new profile will be based on a profile named
BASE-ID. The base profile location is determined with these steps:
1.If BASE-ID starts with prefix custom/ it
is a custom profile.
2.Try if BASE-ID is found in vendor
profiles.
3.Try if BASE-ID is found in default
profiles.
4.Return an error.
--base-on-default
The base profile is a default profile even if it is found
also within vendor profiles.
--symlink-meta
Meta files, such as README and REQUIREMENTS
will be symbolic links to the origin profile files instead of their
copy.
--symlink-nsswitch
nsswitch.conf template will be symbolic link to
the origin profile file instead of its copy.
--symlink-pam
PAM templates will be symbolic links to the origin
profile files instead of their copy.
--symlink-dconf
dconf templates will be symbolic links to the
origin profile files instead of their copy.
--symlink=FILE,-s=FILE
Create a symbolic link for a template file FILE
instead of creating its copy. This option can be passed multiple times.
BACKUP COMMANDS¶
These commands can be used to manage backed up configurations.
backup-list [-r, --raw]
Print available backups. If --raw option is
specified, the command will print only backup names without any formatting and
additional information.
backup-remove BACKUP
Permanently delete backup named BACKUP.
backup-restore BACKUP
Restore configuration from backup named BACKUP.
Note: this will overwrite current configuration.
COMMON OPTIONS¶
These options are available with all commands.
--debug
Print debugging information and error messages.
--trace
Print information about what the tool is doing.
--warn
Print information about unexpected situations that do not
affect the program execution but may indicate some undesired situations (e.g.
unexpected file in a profile directory).
NSSWITCH.CONF MANAGEMENT¶
Authselect generates /etc/nsswitch.conf and does not allow any
user changes to this file. Such changes are detected and authselect will
refuse to write any system configuration unless a --force option is
provided to the select command. This mechanism prevents authselect
from overwriting anything that does not match any available profile.
Any user changes to nsswitch maps must be done in file
/etc/authselect/user-nsswitch.conf. When authselect generates new
nsswitch.conf it reads this file and combines it with configuration
from selected profile. The profile configuration takes always precedence. In
other words, profiles do not have to set all nsswitch maps but can set only
those that are relevant to the profile. If a map is set within a profile, it
always overwrites the same map from user-nsswitch.conf.
Example 1.
# "sssd" profile
$ cat /usr/share/authselect/default/sssd/nsswitch.conf
passwd: sss files systemd
group: sss files systemd
netgroup: sss files
automount: sss files
services: sss files
sudoers: files sss {include if "with-sudo"}
$ cat /etc/authselect/user-nsswitch.conf
passwd: files sss
group: files sss
hosts: files dns myhostname
sudoers: files
$ authselect select sssd
# passwd and group maps from user-nsswitch.conf are ignored
$ cat /etc/nsswitch.conf
passwd: sss files systemd
group: sss files systemd
netgroup: sss files
automount: sss files
services: sss files
hosts: files dns myhostname
sudoers: files
$ authselect select sssd with-sudo
# passwd, group and sudoers maps from user-nsswitch.conf are ignored
$ cat /etc/nsswitch.conf
passwd: sss files systemd
group: sss files systemd
netgroup: sss files
automount: sss files
services: sss files
sudoers: files sss
hosts: files dns myhostname
TROUBLESHOOTING¶
How can I tell if my system is using authselect?¶
Use authselect check. The output will tell you if you have
1) configuration generated by authselect 2) non-authselect configuration or
3) configuration that was generated by authselect but modified manually at
some point.
Is nsswitch.conf supposed to be a symbolic link now?¶
Authselect generates your system configuration from scratch and
stores it at /etc/authselect. System files are then created as symbolic
links to this directory. Symbolic links are used to make it clear that
authselect is now owning your configuration and should be used instead of
any manual modification.
Error: Unexpected changes to the configuration were detected.¶
For example:
[error] [/etc/authselect/nsswitch.conf] does not exist!
[error] [/etc/nsswitch.conf] is not a symbolic link!
[error] [/etc/nsswitch.conf] was not created by authselect!
[error] Unexpected changes to the configuration were detected.
[error] Refusing to activate profile unless those changes are removed or overwrite is requested.
This means that your configuration is unknown to authselect and as
such it will not be modified. To fix this, please call authselect
select with --force parameter to say that it is all right to
overwrite it.
RETURN CODES¶
The authselect can return these exit codes:
•0: Success.
•1: Generic error.
•2: Profile or configuration was not found or the
system was not configured with authselect.
•3: Current configuration is not valid, it was
edited without authselect.
•4: System configuration must be overwritten to
activate an authselect profile, --force parameter is needed.
•5: Executed command must be run as root.
GENERATED FILES¶
Authselect creates and maintains the following files to configure
system identity and authentication providers properly.
/etc/nsswitch.conf
Name Service Switch configuration file.
/etc/pam.d/system-auth
PAM stack that is included from nearly all individual
service configuration files.
/etc/pam.d/password-auth, smartcard-auth,
fingerprint-auth
These PAM stacks are for applications which handle
authentication from different types of devices via simultaneously running
individual conversations instead of one aggregate conversation.
/etc/pam.d/postlogin
The purpose of this PAM stack is to provide a common
place for all PAM modules which should be called after the stack configured in
system-auth or the other common PAM configuration files. It is included from
all individual service configuration files that provide login service with
shell or file access. NOTE: the modules in the postlogin configuration file
are executed regardless of the success or failure of the modules in the
system-auth configuration file.
/etc/dconf/db/distro.d/20-authselect
Changes to dconf database. The main uses case of this
file is to set changes for gnome login screen in order to enable or disable
smartcard and fingerprint authentication.
/etc/dconf/db/distro.d/locks/20-authselect
This file define locks on values set in dconf
database.